home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / pc / STK100.ZIP / DWS.H < prev    next >
Encoding:
C/C++ Source or Header  |  1995-02-17  |  10.2 KB  |  323 lines
  1. /******************************************************************************
  2. File:          dws.h
  3. Version:     1.0
  4. Tab stops: every 2 collumns
  5. Project:     The Sound ToolKit
  6. Copyright: 1994 DiamondWare, Ltd.  All rights reserved.
  7. Written:     by Keith Weiner and Erik Lorenzen
  8. Purpose:     Contains declarations for the DW Sound ToolKit
  9. History:     KW 08/24/94 Started
  10.                      EL 02/17/95 Finalized for v1.0
  11. ******************************************************************************/
  12.  
  13.  
  14. #ifndef dws_INCLUDE
  15.  
  16.     #define dws_INCLUDE
  17.  
  18.  
  19. /*****************************************************************************/
  20.     /*
  21.      . The following is the complete list of possible values for dws_ErrNo.
  22.      . dws_ErrNo may be set by any dws_ function.  Check its value whenever
  23.      . the return value of a dws_ function is 0 (error).
  24.     */
  25.     #define dws_EZERO                                                      0     //no error
  26.  
  27.     /* The following 3 errors may be triggered by any dws_ function */
  28.     #define dws_NOTINITTED                                             1
  29.     #define dws_ALREADYINITTED                                     2
  30.     #define dws_NOTSUPPORTED                                         3
  31.  
  32.     /* The following 4 errors may be triggered by dws_DetectHardWare */
  33.     #define dws_DetectHardware_UNSTABLESYSTEM      4
  34.     #define dws_DetectHardware_BADBASEPORT             5
  35.     #define dws_DetectHardware_BADDMA                      6
  36.     #define dws_DetectHardware_BADIRQ                      7
  37.  
  38.     /* The following error may be triggered by dws_Kill */
  39.     #define dws_Kill_CANTUNHOOKISR                             8
  40.  
  41.     /* The following error may be triggered by any dws_X (mixer) function */
  42.     #define dws_X_BADINPUT                                             9
  43.  
  44.     /* The following 3 errors may be triggered by any dws_D (dig) function */
  45.     #define dws_D_NOTADWD                                              10
  46.     #define dws_D_NOTSUPPORTEDVER                              11
  47.     #define dws_D_INTERNALERROR                                  12
  48.  
  49.     /* The following error may be triggered by dws_DPlay */
  50.     #define dws_DPlay_NOSPACEFORSOUND                      13
  51.  
  52.     /* The following 2 errors may be triggered by dws_DSetRate */
  53.     #define dws_DSetRate_FREQTOLOW                             14
  54.     #define dws_DSetRate_FREQTOHIGH                          15
  55.  
  56.     /* The following 3 errors may be triggered by dws_MPlay */
  57.     #define dws_MPlay_NOTADWM                                      16
  58.     #define dws_MPlay_NOTSUPPORTEDVER                      17
  59.     #define dws_MPlay_INTERNALERROR                          18
  60. /*---------------------------------------------------------------------------*/
  61.  
  62.  
  63.     /*
  64.      . The follwing section defines bitfields which are used by various
  65.      . dws_ functions.    Each bit in a bitfield, by definition, may be
  66.      . set/reset independantly of all other bits.
  67.     */
  68.  
  69.     /* The following 2 consts indicate the capabilities of the user's hardware */
  70.     #define dws_capability_FM                                      0x0001
  71.     #define dws_capability_DIG                                     0x0002
  72.  
  73.     /* The following 2 consts indicate the status of specified digital sounds */
  74.     #define dws_DSOUNDSTATUSPLAYING                          0x0001
  75.     #define dws_DSOUNDSTATUSSEQUENCED                      0x0002
  76.  
  77.     /* The following 2 consts indicate the status of music playback */
  78.     #define dws_MSONGSTATUSPLAYING                             0x0001
  79.     #define dws_MSONGSTATUSPAUSED                              0x0002
  80. /*****************************************************************************/
  81.  
  82.  
  83.  
  84.     /*
  85.      . The following 3 types are used by the STK
  86.      .
  87.      . If you are already typedefing these names, simply put the line
  88.      .     #define stddef_INCLUDE
  89.      . before the line
  90.      .     #include <dws.h>
  91.      . in every source file which references the STK.
  92.     */
  93.     #ifndef stddef_INCLUDE
  94.         typedef unsigned char byte;
  95.         typedef unsigned int    word;
  96.         typedef unsigned long dword;
  97.     #endif
  98. /*****************************************************************************/
  99.  
  100.  
  101.  
  102.     /*
  103.      . The following section typedefs the structs used by the STK.    In each
  104.      . case, the user must create an instance of the struct prior to making
  105.      . a call to an STK function which takes a pointer to it.  The STK does
  106.      . not keep a pointer to any of these structs internally; after the call
  107.      . returns, you may deallocate it, if you wish.
  108.      .
  109.      . NB: The STK _does_ keep pointers to songs and digitized sound buffers!
  110.     */
  111.  
  112.  
  113.     /*
  114.      . dws_DetectHardWare can be told _not_ to autodetect particular values
  115.      . about the installed hardware.    This is useful if detecting DMA channel,
  116.      . for example, consistently causes a machine lockup.  To override the
  117.      . autodetect for a setting (causing the STK to accept it on faith),
  118.      . set the corresponding field in this struct to the correct value.
  119.      . Otherwise, set the field to ffff hex.    Since the autodetect is reliable,
  120.      . this is the recommended course of action, except in cases of known
  121.      . problems.
  122.     */
  123.     typedef struct
  124.     {
  125.         word baseport;            //base address of sound card (often 220 hex)
  126.  
  127.         word digdma;                //DMA channel
  128.         word digirq;                //IRQ level
  129.  
  130.         byte reserved[10];
  131.  
  132.     } dws_DETECTOVERRIDES;
  133.  
  134.  
  135.     /*
  136.      . A pointer to this struct is passed to dws_DetectHardWare, which fills
  137.      . it in.  It is then passed unmodified to dws_Init.    If you plan on
  138.      . writing this struct out to a file, it's important that you write
  139.      . the entire contents.  There is information (for internal STK use only)
  140.      . in the reserved[] field!
  141.     */
  142.     typedef struct
  143.     {
  144.         word baseport;            //base address of sound card (often 220 hex)
  145.  
  146.         word capability;        //see #defines, above
  147.  
  148.         /* The following 3 fields are only valid if FM music is supported */
  149.         word mustyp;                //0=none, 1=OPL2
  150.         word musnchan;            //1=mono
  151.         word musnvoice;         //number of voices supported by hardware (11 for FM)
  152.  
  153.         /* The following 4 fields are only valid if digitized sound is supported */
  154.         word dignbits;            //0=none, 8=8 bit
  155.         word dignchan;            //1=mono
  156.         word digdma;                //DMA channel
  157.         word digirq;                //IRQ level
  158.  
  159.         word mixtyp;                //1=software, 2+ is hardware
  160.  
  161.         byte reserved[44];    //there are important values in here...
  162.  
  163.     } dws_DETECTRESULTS;
  164.  
  165.  
  166.     /*
  167.      . A pointer to this struct is passed as a parameter to dws_Init.  This
  168.      . allows the user to tell the STK to use less than the full capabilities
  169.      . of the installed sound hardware, and/or the user's sound board
  170.      . may not support every feature of the STK.
  171.     */
  172.     typedef struct
  173.     {
  174.         word musictyp;                //0=No Music, 1=OPL2
  175.  
  176.         word digtyp;                    //0=No Dig, 8=8bit
  177.         word digrate;                 //sampling rate, in Hz
  178.         word dignvoices;            //number of voices (up to 16)
  179.         word dignchan;                //1=mono
  180.  
  181.         byte reserved[6];
  182.  
  183.     } dws_IDEAL;
  184.  
  185.  
  186.     /*
  187.      . A pointer to this struct is passed to dws_DPlay.
  188.      . Note that the soundnum field is filled in by dws_DPlay as a return value.
  189.     */
  190.     typedef struct
  191.     {
  192.         byte _far *snd;             //pointer to buffer which holds a .DWD file
  193.         word count;                     //number of times to play, or 0=infinite loop
  194.         word priority;                //higher numbers mean higher priority
  195.         word presnd;                    //soundnum to sequence sound _after_
  196.         word soundnum;                //dws_DPlay returns a snd number from 10-65535
  197.  
  198.         byte reserved[20];
  199.  
  200.     } dws_DPLAY;
  201.  
  202.  
  203.     /* A pointer to this struct is passed to dws_MPlay. */
  204.     typedef struct
  205.     {
  206.         byte _far *track;         //pointer to buffer which holds a .DWM file
  207.         word count;                     //number of times to play, or 0=infinite loop
  208.  
  209.         byte reserved[10];
  210.  
  211.     } dws_MPLAY;
  212. /*****************************************************************************/
  213.  
  214.  
  215.  
  216.     #ifdef __cplusplus
  217.         extern "C" {
  218.     #endif
  219. /*****************************************************************************/
  220.  
  221.  
  222.     /*
  223.      . This function is callable at any time.  It returns the number of the
  224.      . last error which occured.
  225.     */
  226.     word    _far _pascal dws_ErrNo(void);
  227. /*---------------------------------------------------------------------------*/
  228.  
  229.  
  230.     /*
  231.      . This function is called at the end of the timer ISR (interrupt service
  232.      . routine).    If you're using the optional DWT (DW Timer), this happens
  233.      . automagically.  If you wrote your own timer handler routine, you must
  234.      . call this function regularly.
  235.     */
  236.     void    _far _pascal _loadds _saveregs dws_Update(void);
  237. /*---------------------------------------------------------------------------*/
  238.  
  239.  
  240.     /*
  241.      . Each function in this section has a boolean return value.    A 0 (false)
  242.      . indicates that the function failed in some way.    In this case, call
  243.      . dws_ErrNo to get the specific error.  Otherwise, a return value of 1
  244.      . (true) indicates that all is well.
  245.     */
  246.     word    _far _pascal dws_DetectHardWare(dws_DETECTOVERRIDES _far *dov,
  247.                                                                                     dws_DETECTRESULTS _far *dr);
  248.  
  249.     word    _far _pascal dws_Init(dws_DETECTRESULTS _far *dr,
  250.                                                                 dws_IDEAL _far *ideal);
  251.  
  252.     /*
  253.      . If the program has called dws_Init, it _MUST_ call dws_Kill before it
  254.      . terminates.
  255.      .
  256.      . NB: Trap critical errors.    Don't let DOS put up the
  257.      .         "Abort, Retry, Fail?" text.    ('sides, it'll destroy your pretty gfx)
  258.     */
  259.     word    _far _pascal dws_Kill(void);
  260.  
  261.  
  262.     /*
  263.      . The following 3 functions comprise the mixer section of the STK.  A
  264.      . value of 0 turns a channel off; a value of 255 is the loudest.
  265.     */
  266.     word    _far _pascal dws_XMaster(word volume);
  267.  
  268.     word    _far _pascal dws_XMusic(word volume);
  269.  
  270.     word    _far _pascal dws_XDig(word volume);
  271.  
  272.  
  273.     /*
  274.      . The following 10 functions comprise the digitized sound functions of
  275.      . the STK.  See the documentation for complete details.
  276.     */
  277.     word    _far _pascal dws_DPlay(dws_DPLAY _far *dplay);
  278.  
  279.     word    _far _pascal dws_DSoundStatus(word soundnumber, word _far *result);
  280.  
  281.     word    _far _pascal dws_DSetRate(word frequency);
  282.  
  283.     word    _far _pascal dws_DGetRate(word _far *result);
  284.  
  285.     /* This function is callable at any time*/
  286.     word    _far _pascal dws_DGetRateFromDWD(byte _far *snd, word _far *result);
  287.  
  288.     word    _far _pascal dws_DDiscard(word soundnum);
  289.  
  290.     word    _far _pascal dws_DDiscardAO(byte _far *snd);
  291.  
  292.     word    _far _pascal dws_DClear(void);                            //Affects all sounds
  293.  
  294.     word    _far _pascal dws_DPause(void);                            //Affects all sounds
  295.  
  296.     word    _far _pascal dws_DUnPause(void);                        //Affects all sounds
  297.  
  298.  
  299.     /*
  300.      . The following 5 functions comprise the music functions of the STK.
  301.      . See the documentation for complete details.
  302.     */
  303.     word    _far _pascal dws_MPlay(dws_MPLAY _far *mplay);
  304.  
  305.     word    _far _pascal dws_MSongStatus(word _far *result);
  306.  
  307.     word    _far _pascal dws_MClear(void);                            //Kill playing song
  308.  
  309.     word    _far _pascal dws_MPause(void);                            //Pauses music playback
  310.  
  311.     word    _far _pascal dws_MUnPause(void);                        //UnPauses music playback
  312. /*****************************************************************************/
  313.  
  314.  
  315.  
  316.     #ifdef __cplusplus
  317.         }
  318.     #endif
  319.  
  320.  
  321.  
  322. #endif
  323.